home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Gold Collection / Software Vault - The Gold Collection (American Databankers) (1993).ISO / cdr10 / bagtag2.zip / CTAGS.DOC < prev    next >
Lisp/Scheme  |  1993-06-19  |  6KB  |  116 lines
  1. 19Jun93                        Notes on CTAGS               Barry Goldstein
  2.  
  3. 29Nov92
  4. 1. This is an upgrade to the Brief version of the UNIX/VI tagging system. I
  5.     took off from earlier versions by Yellow Pig XVII, The Shaman, Paul
  6.     Verket, Michael Denio, Morris Maynard, Edward Diener, and Sky Schulz. In
  7.     particular, I carved up the code found in CTAGS5.ZIP.
  8.  
  9. 2. Files:
  10.     CTAGS.C: Source code for the program that prepares the tag files.
  11.     CTAGS.COM: That code compiled (Microsoft C6.0a), and linked using setargv
  12.                 and an improved version of wild.c (so wild card specs like 
  13.                 *e.[ch] will work).
  14.  
  15.     WILDS.OBJ: Small model object for the improved wild card command line
  16.                 file spec expander.
  17.  
  18.     CTAGS.CB: Source code for the Brief macro that uses the tag files.
  19.     CTAGS.CM: That code compiled (Brief for DOS, Version 3.1; macros will
  20.                 work with OS/2 as well).
  21.  
  22.     GOTO.CB, GOTO.CM: Source code for the macro I assign to Alt-g, to allow
  23.                 quick access to tags, line numbers, next or previous function 
  24.                 headers.
  25.  
  26.     BAG_UTIL.CB, BAG_UTIL.CB: Contains the macro for grabbing a token at or
  27.                 near the cursor position (GetIdentifier) and some others.
  28.  
  29. 3. To incorporate these into your Brief setup, in your initials macro, add
  30.     the following lines:
  31.         (autoload "ctags" "ctag" "tag")
  32.         (autoload "goto" "goto")
  33.         (assign_to_key "<Alt-g>" "goto")
  34.         (autoload "util" "GetIdentifier")
  35.  
  36. 4. The tagging macros search for tag files (named CTAGS.TAG) in the
  37.     following order:
  38.         the current directory
  39.         the directory containing the file in the current edit buffer (if
  40.             different)
  41.         directories on the path specified by a CTAGS environment variable,
  42.             e.g.:
  43.              set CTAGS=D:\MYWORK;D:\MYWORK\UTILS;D:\MYWORK\INCLUDES
  44.  
  45. 5. Run ctags.com against your source files, in each directory of concern,
  46.     re-directing its output to ctags.tag. Run ctags without any arguments
  47.     for a usage message; essentially you want something like
  48.               ctags *.c *.h >ctags.tag 
  49.     Flags (see usage) can be interspersed with file specs and apply to
  50.     following files. The default is to tag every kind of thing it knows
  51.     about. Flags on the command line are indicated by either "-" or "/".
  52.     Flags can be combined and the sense of the flags is reversed by a "!".
  53.     E.g.: -!seu will turn off structure, enum, and union tagging.
  54.  
  55. 6. Please see the headers of the C and CB files for details of past history,
  56.     features, and possible future features.
  57.  
  58. 7. New features: 
  59.     It now tags functions, #defines, typedefs, structs, unions, enums, and
  60.     enum constants; except for functions, command line arguments allow for
  61.     not tagging any of these constructs.
  62.  
  63.     It now tags any of these things (in so far as they are legal) WITHIN
  64.     code bound by braces, so it will find #defines within a structure
  65.     definition, or structs within a function body, and such like.
  66.  
  67. 8. The finite state machine parser is pretty simple minded, but it will work
  68.     with all but really idiosyncratic styles of coding. I've toyed with the
  69.     idea of re-doing the whole thing using lex/yacc, but have not gotten
  70.     quite that obsessed with it. The syntax spec would have to combine parts
  71.     of the C pre-processor scan with the compiler scan itself.
  72.  
  73. 9. One possible line of development is to process #if stuff, at least with
  74.     symbols defined on the command line (/DDEBUG, e.g.), if not with #defines
  75.     within the program. #if, #if[n]def, #if [!]defined, #else, #elif, #endif,
  76.     is as far as I'm willing to go, with simple, atomic operands (such as
  77.     #ifdef FOO). Anything further would re-invent the pre-processor, and see
  78.     item 7 above.
  79.  
  80. 10. The goto macro extends the standard goto_line usually assigned to Alt-g.
  81.     It takes a string argument and parses it so:
  82.         if null (you just hit Enter), it calls ctag which picks up the token
  83.             at the cursor and searches for the tag
  84.         if "+" or "-", it searches down or up for the nearest thing that
  85.             looks like a function header (same search used in improved
  86.             versions of the routines.cb macro)
  87.         if numeric, it calls goto_line
  88.         if anything else, it calls tag to search for the argument.
  89.     Hitting Esc punts.
  90.  
  91. 11. The GetIdentifier macro is a little more generous with what it takes for
  92.     a valid token than the C and CB compilers. But then again, ctags isn't
  93.     meant to replace LINT or the compiler.
  94.  
  95. 12. I can be reached via Compuserve (73467,1357), though I only check there
  96.     weekly. E-mail at BARRY_GOLDSTEIN@CRD.LOTUS.COM or via any BBS (Brief
  97.     conference) that might be echoed to the Channel 1 BBS in Cambridge, MA 
  98.     (617-354-8873)
  99.  
  100. 13. You may do whatever you want with these programs. No promises. No
  101.     charge. Comments are welcome.
  102.  
  103. 19Jun93
  104. 14. Found a bug: a structure definition without a body
  105.  
  106.                         struct foo xxx;
  107.  
  108.     screws up scan. Has to quit and not tag such things if it finds a
  109.     variable name before the opening brace. Same problem (or worse for enum 
  110.     or union defined without a body.
  111.  
  112. 15. Fixed another bug, that missed struct, union, enum definitions after
  113.     some other "word" (such as static, or _far, _FAR_, etc.).
  114.  
  115. --------------------------- end of ctags.doc file ---------------------------
  116.